[release-1.7.3]: https://github.com/HuolalaTech/page-spy-web/releases/tag/v1.7.3
[public-data-event]: https://github.com/HuolalaTech/page-spy/blob/main/docs/plugin_zh.md#행동-규약

import modalImg from '@/assets/image/screenshot/modal.png';
import replayImg from '@/assets/image/screenshot/replay-page.png';
import replayGif from '@/assets/image/screenshot/replay-page.gif';
import mpDataHarborImg from '@/assets/image/screenshot/mp-data-harbor.png';

## 개요#what

로그 재생은 오프라인 디버깅 기능으로, 문제 발생 후 당시의 런타임 데이터를 확인하고 분석할 수 있습니다. 기록 로그를 재생하여 비디오처럼 문제 시나리오를 재현할 수 있으며, 실시간으로 디버깅 엔드에 연결할 필요가 없습니다.

<a href={replayGif} target="_blank">
  <img src={replayGif} />
</a>

## 왜 필요한가#why

PageSpy의 온라인 디버깅 기능은 강력하지만 클라이언트와 디버깅 엔드포인트가 동시에 온라인 상태여야 합니다. 이는 다음과 같은 제한을 가져옵니다:

- **높은 인력 비용**: 단일 문제 디버깅을 위해 개발자와 테스터가 동시에 온라인 상태여야 함
- **불안정한 연결**: 클라이언트가 백그라운드로 전환되거나 네트워크 변동으로 연결이 끊어질 수 있음
- **실시간 전송 압력**: 데이터 볼륨과 네트워크 전송 성능을 고려해야 함

이러한 문제를 해결하기 위해 PageSpy는 [1.7.3][release-1.7.3] 버전에서 로그 재생 기능을 도입하여 디버깅을 더욱 유연하고 자유롭게 만들었습니다.

## 개시사용#start-using

### 브라우저에서 사용#browser

온라인 디버깅과 오프라인 재생을 포함한 PageSpy의 전체 기능이 필요한 경우 다음과 같이 통합하세요:

#### 1단계: SDK 및 플러그인 통합#step-1

```html
<html>
  <head>
    <!-- 1. PageSpy 로드 -->
    <script src="{deployUrl}/page-spy/index.min.js"></script>
    <!-- 2. DataHarbor 플러그인 로드: 오프라인 로그 데이터 캐시, 업로드/다운로드 기능 제공 -->
    <script src="{deployUrl}/plugin/data-harbor/index.min.js"></script>
    <!-- 3. RRWeb 플러그인 로드: 사용자 작업 기록(선택 사항) -->
    <script src="{deployUrl}/plugin/rrweb/index.min.js"></script>

    <script>
      // 4. 플러그인 등록, config 정보는 다음 참조: https://github.com/HuolalaTech/page-spy/blob/main/packages/page-spy-plugin-data-harbor
      PageSpy.registerPlugin(new DataHarborPlugin(config));
      PageSpy.registerPlugin(new RRWebPlugin());

      // 5. PageSpy 인스턴스화
      window.$pageSpy = new PageSpy({
        // SDK와 디버그 측이 실시간 연결을 설정하지 않으려면 오프라인 모드를 활성화할 수 있습니다
        // offline: true
      });
    </script>
  </head>
</html>
```

통합이 성공하면 페이지 오른쪽 하단에 PageSpy 플로팅 볼이 나타납니다. 플로팅 볼을 클릭하면 팝업에 업로드 및 다운로드 버튼이 포함됩니다.

<a href={modalImg} target="_blank">
  <img src={modalImg} />
</a>

업로드 또는 다운로드 버튼을 클릭하여 오프라인 로그 데이터를 저장하세요.

#### 2단계: 로그 재생#step-2

디버그 측에 들어가서 상단 메뉴의 "디버그 시작 - 로그 재생"을 클릭하여 재생 목록 페이지로 이동한 후, 이전 단계에서 업로드/다운로드한 json 데이터를 선택하면 재생 기능을 사용할 수 있습니다!

<a href={replayImg} target="_blank">
  <img src={replayImg} />
</a>

#### 플러그인 설명#plugins

- **DataHarborPlugin**: 오프라인 로그 데이터를 수집 및 저장하고, 업로드/다운로드 기능 제공
- **RRWebPlugin**(선택 사항): [rrweb]({VITE_PLUGIN_RRWEB})를 사용하여 DOM 업데이트 및 사용자 작업을 기록합니다. 디버깅 클라이언트의 "로그 재생" 패널 왼쪽에서 페이지 작업 녹화를 볼 수 있습니다

### O-Spy 사용하기#use-ospy

오프라인 로그 재생 기능만 필요한 경우 [O-Spy](/o-spy) 사용을 권장합니다. 서버 배포가 필요 없는 플러그 앤 플레이 SDK로, PageSpy, DataHarborPlugin, RRWebPlugin의 모범 사례 구성이 내장되어 있습니다.

프레임워크에 구애받지 않으며 어떤 방법으로든 통합할 수 있습니다:

import { ImportGuide } from '@/pages/OSpy/components/ImportGuide';

<ImportGuide />

정상적으로 도입되면 우측 하단에 "문제 피드백" 드래그 가능한 컴포넌트가 나타납니다.

#### 사용자 정의 테마 예시#customize-example

import { CustomizeExample } from '@/pages/OSpy/components/Customize';

<CustomizeExample />

### 미니프로그램에서 사용#mp

미니프로그램 환경에서도 오프라인 로그 재생을 지원합니다. 단계는 다음과 같습니다:

#### 1단계: 미니프로그램 전용 플러그인 설치#mp-step-1
```bash
yarn add @huolala-tech/page-spy-plugin-mp-data-harbor
```

#### 2단계: 플러그인 등록#mp-step-2
```ts
import PageSpy from '@huolala-tech/page-spy-wechat';
import DataHarborPlugin from '@huolala-tech/page-spy-plugin-mp-data-harbor';

// 플러그인 등록, config 정보는 다음 참조: https://github.com/HuolalaTech/page-spy/blob/main/packages/page-spy-plugin-mp-data-harbor
const $dataHarborPlugin = new DataHarborPlugin(config)
PageSpy.registerPlugin($dataHarborPlugin);

const $pageSpy = new PageSpy({
  // ...
})
```

#### 3단계: 오프라인 로그 업로드#mp-step-3

오프라인 로그를 업로드하는 방법에는 두 가지가 있습니다:

**방법 1: 코드 호출**

```ts
$dataHarborPlugin.upload().then(() => {
  console.log('업로드 성공');
})
```

**방법 2: 디버깅 메뉴 사용**

미니프로그램 DataHarbor 플러그인을 등록하면 PageSpy 디버깅 메뉴에 "오프라인 로그 업로드" 버튼이 나타납니다. 클릭하여 업로드하세요:

<a href={mpDataHarborImg} target="_blank">
  <img style={{width: 375}} src={mpDataHarborImg} />
</a>

## 연伸阅读#read-more

### 작동 원리#how-it-works

로그 재생은 [DataHarborPlugin]({VITE_PLUGIN_DATA_HARBOR}) 플러그인을 기반으로 구현됩니다. 이 플러그인은 PageSpy 내부의 [`"public-data"` 이벤트](./plugins#convention)를 리슨하여 런타임에 생성되는 모든 데이터를 자동으로 수집합니다.

### 플랫폼 차이#platform-differences

로그 재생 기능에서 플랫폼마다 다음과 같은 차이가 있습니다:

| 기능 | 브라우저 | 미니프로그램 |
| --- | --- | --- |
| 데이터 업로드 | ✅ 지원 | ✅ 지원 |
| 데이터 다운로드 | ✅ 지원 | ❌ 미지원 |
| UI 녹화(RRWebPlugin) | ✅ 지원 | ❌ 미지원 |

### FAQ#faq

#### 1. 수동으로 로그를 업로드/다운로드하는 방법은?

자세한 설명은 [DataHarborPlugin API 문서](./data-harbor#onOfflineLog)를 참조하세요.

#### 2. 오프라인 로그 데이터는 어디에 저장되나요?

DataHarborPlugin이 데이터를 수신한 후의 처리 흐름:

1. 데이터는 먼저 메모리 배열에 저장됨
2. 메모리의 데이터가 임계값(기본 10MB)에 도달하면 자동으로 임시 파일에 기록됨
3. 사용자는 언제든지 데이터를 서버에 업로드하거나 로컬에 저장하여 다운로드할 수 있음

메모리 임계값을 사용자 정의할 수 있습니다:

```ts
new DataHarborPlugin({
  maximum: 1 * 1024 * 1024, // 메모리의 데이터가 1MB에 도달하면 임시 파일에 기록
})
```

#### 3. 오프라인 로그가 애플리케이션 성능에 영향을 주나요?

DataHarborPlugin은 성능 최적화가 되어 있습니다:

- 비동기 처리를 사용하여 메인 스레드를 차단하지 않음
- 메모리 사용을 자동으로 제어하여 메모리 오버플로 방지
- 저장 전 데이터를 압축하여 공간 사용 감소